Troubleshooting & FAQ

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

10. Appendices

This document provides comprehensive troubleshooting and FAQ guidance for the SuperSet Telegram Notification Bot. It covers systematic diagnostics for bot communication, database connectivity, update scheduling, and notification delivery. It also includes performance tuning, memory optimization, error recovery, configuration FAQs, debugging techniques, escalation procedures, and production monitoring recommendations.

The bot is organized as a modular Python application with:

• CLI entry point and daemon control

• Service-oriented architecture with dependency injection

• Dedicated servers for bot, scheduler, and webhook

• Database abstraction and services for notifications, users, and data processing

• Runners for update and notification dispatch

Diagram sources

• app/main.py

• app/core/daemon.py

• app/core/config.py

• app/servers/bot_server.py

• app/servers/scheduler_server.py

• app/servers/webhook_server.py

• app/services/database_service.py

• app/services/notification_service.py

• app/services/telegram_service.py

• app/services/web_push_service.py

• app/runners/update_runner.py

• app/runners/notification_runner.py

• app/clients/db_client.py

Section sources

• README.md

• app/main.py

• CLI and daemon control: centralized command routing, daemonization, logging initialization

• Servers: Telegram bot, scheduler, and webhook FastAPI server

• Services: database abstraction, notification orchestration, Telegram and Web Push channels

• Runners: update fetching and notification dispatch

• Clients: database client for MongoDB connectivity

Key responsibilities:

• Configuration and logging: type-safe settings, environment loading, log rotation

• Bot server: command handlers, user registration, stats, admin commands

• Scheduler server: cron-based update jobs, official data scraping

• Webhook server: health checks, push subscription APIs, broadcast endpoints

• Database service: CRUD operations, statistics, duplicate prevention

• Notification service: channel routing, batching, delivery tracking

• Telegram service: message formatting, rate limiting, long message splitting

• Web push service: VAPID authentication, subscription management hooks

Section sources

• app/core/config.py

• app/servers/bot_server.py

• app/servers/scheduler_server.py

• app/servers/webhook_server.py

• app/services/database_service.py

• app/services/notification_service.py

• app/services/telegram_service.py

• app/services/web_push_service.py

• app/runners/update_runner.py

• app/runners/notification_runner.py

• app/clients/db_client.py

The system separates concerns across CLI, servers, services, and runners. The scheduler and bot servers operate independently, while the webhook server exposes REST endpoints for integrations. Services encapsulate domain logic and depend on the database client for persistence.

Diagram sources

• app/servers/bot_server.py

• app/services/database_service.py

• app/services/telegram_service.py

Section sources

• README.md

Database Connectivity and Persistence#

• Connection lifecycle: client creates connection, initializes collections, validates with ping

• Database service wraps collections and provides CRUD, statistics, and duplicate prevention

• Indexing strategy optimized for frequent queries (unsent notices, active users, timestamps)

Diagram sources

• app/clients/db_client.py

Section sources

• app/clients/db_client.py

• app/services/database_service.py

• docs/DATABASE.md

Telegram Bot Communication#

• Command handlers for start, stop, status, stats, and admin commands

• Message formatting and long message splitting with rate limiting

• Broadcast to all active users with success/failure accounting

Diagram sources

• app/servers/bot_server.py

• app/services/telegram_service.py

Section sources

• app/servers/bot_server.py

• app/services/telegram_service.py

Notification Delivery Pipeline#

• NotificationService orchestrates channels and tracks delivery

• DatabaseService provides unsent notices and marks as sent upon successful broadcast

• TelegramService handles rate limits and long messages; WebPushService handles VAPID and subscription removal on expiration

Diagram sources

• app/runners/notification_runner.py

• app/services/notification_service.py

• app/services/database_service.py

• app/services/telegram_service.py

• app/services/web_push_service.py

Section sources

• app/services/notification_service.py

• app/services/database_service.py

• app/services/telegram_service.py

• app/services/web_push_service.py

• app/runners/notification_runner.py

Update Scheduling and Data Processing#

• SchedulerServer sets up cron jobs for updates and official data scraping

• UpdateRunner fetches notices/jobs from SuperSet and processes with job enrichment

• Email processing orchestrates LLM-based placement extraction and notice classification

Diagram sources

• app/servers/scheduler_server.py

• app/runners/update_runner.py

• app/runners/notification_runner.py

Section sources

• app/servers/scheduler_server.py

• app/runners/update_runner.py

• app/runners/notification_runner.py

Webhook Server and Integrations#

• Health endpoints, push subscription management, and broadcast APIs

• Dependency injection for services and graceful degradation when optional dependencies are missing

Diagram sources

• app/servers/webhook_server.py

• app/services/web_push_service.py

Section sources

• app/servers/webhook_server.py

• app/services/web_push_service.py

• Loose coupling via dependency injection and factory functions

• Centralized configuration and logging across components

• Clear separation between servers, services, and runners

Diagram sources

• app/main.py

• app/servers/bot_server.py

• app/servers/scheduler_server.py

• app/servers/webhook_server.py

• app/services/database_service.py

• app/services/notification_service.py

• app/runners/update_runner.py

• app/runners/notification_runner.py

• app/clients/db_client.py

Section sources

• app/main.py

• app/core/config.py

• Database queries: leverage indexes and projections; avoid loading entire collections

• Asynchronous design: ensure non-blocking operations in async contexts

• Batch operations: bulk writes and updates to reduce overhead

• Memory usage: clear caches, avoid circular references, monitor RSS

• LLM model selection: choose appropriate model for speed vs accuracy trade-offs

[No sources needed since this section provides general guidance]

Connection Issues#

• MongoDB connection failures

  • Validate connection string format and credentials

  • Check IP whitelist and network access

  • Confirm firewall allows outbound connections to port 27017

  • Test connectivity with ping and curl

  • Use the provided connection test script in troubleshooting docs

• Email IMAP authentication failures

  • Ensure 2FA is enabled and app password is used

  • Regenerate app password if needed

• Telegram bot token invalid

  • Verify token format and ensure it is active

  • Check for spaces or typos in the token

Section sources

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

Bot Issues#

• Bot not receiving messages

  • Confirm bot server is running and listening

  • Distinguish between long-polling and webhook modes

  • Ensure user has sent /start and is registered

  • Validate chat ID format and permissions

• Bot commands not responding

  • Check command format and casing

  • Verify admin-only commands require admin ID

  • Respect rate limiting and timing

• Bot crashes unexpectedly

  • Inspect logs for unhandled exceptions

  • Monitor memory usage and consider reducing batch sizes

  • Ensure database reconnection logic is in place

  • Avoid blocking operations in async code paths

Section sources

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

Data Processing Issues#

• Notices not being scraped

  • Validate SuperSet credentials and portal accessibility

  • Check for portal layout changes affecting selectors

  • Review duplicate detection logic and last scraped timestamps

• Placement offers not extracted

  • Verify GOOGLE_API_KEY validity and LLM model configuration

  • Confirm email fetching is functioning

• Duplicate notifications sent

  • Inspect notice ID uniqueness and timestamp handling

  • Check manual updates and sent flags

Section sources

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

Notification Issues#

• Messages not sent to Telegram

  • Reset sent flags if needed and re-send

  • Test Telegram API connectivity manually

  • Validate chat ID format and length limits

• Web push not working

  • Generate and configure VAPID keys

  • Verify user subscriptions exist

  • Ensure service worker is registered on the client

  • Handle expired subscriptions and remove them

Section sources

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

Performance Issues#

• Slow bot response

  • Analyze slow database queries and add indexes

  • Replace blocking I/O with async equivalents

  • Batch operations and reduce per-user loops

  • Tune LLM model for speed if latency is high

• High memory usage

  • Use lazy cursors for large queries

  • Periodically clear caches and finalize objects

  • Investigate circular references and weak references

Section sources

• docs/TROUBLESHOOTING.md

• docs/TROUBLESHOOTING.md

FAQ#

• How often should updates run?

  • Default schedule is three times daily (12 AM, 12 PM, 6 PM IST); adjust via configuration

• Can I run multiple instances?

  • Yes, coordinate via process isolation and database locking

• How do I back up data?

  • Use mongodump against the configured connection string

• How do I add a new data source?

  • Create a service class and integrate via the main CLI or scheduler

• Can I use SQLite instead of MongoDB?

  • Not without rewriting the database abstraction

• How do I change the bot token?

  • Obtain a new token from BotFather and restart the daemon

• How do I see what’s happening?

  • Tail the logs in the configured log directory

• Why aren’t notifications sent at scheduled times?

  • Verify scheduler is enabled, bot is running, and scheduler logs

• Can users filter notifications?

  • Not yet, but options are /start and /stop

• How do I contact support?

  • Use GitHub Issues or the live bot link

Section sources

• docs/TROUBLESHOOTING.md

• docs/CONFIGURATION.md

This troubleshooting guide consolidates practical diagnostics, logging strategies, and resolution steps for the SuperSet Telegram Notification Bot. By following the systematic approaches outlined—covering connection, bot, data processing, notification delivery, performance, and operational FAQs—you can maintain a reliable, production-grade notification system.

[No sources needed since this section summarizes without analyzing specific files]

Systematic Diagnostic Checklist#

• Environment variables validated and loaded

• Database connectivity verified

• Bot server running and reachable

• Scheduler jobs configured and logging

• Notification channels enabled and configured

• Logs reviewed for recent errors and warnings

• Resource usage monitored (CPU, memory, disk)

Section sources

• docs/CONFIGURATION.md

• docs/TROUBLESHOOTING.md

Escalation Procedures#

• Capture logs from all components (bot, scheduler, webhook)

• Provide environment details and configuration excerpts

• Include reproduction steps and error messages

• Engage with community support channels as documented

Section sources

• README.md